package org.javanum.number;

/**
 * Copyright 2010 Scott Fines
 * <p/>
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * <p/>
 * http://www.apache.org/licenses/LICENSE-2.0
 * <p/>
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * <p/>
 * Author: Scott Fines
 * Date: Mar 7, 2010
 */
public interface ComplexField<R extends RealField<R,T>,
                              V extends ComplexField<R,V,T>,
                              T extends Number> extends Field<V> {

    /**
     * <p>Return the modulus of {@code this}</p>
     *
     * <p>The <i>modulus</i> of a complex number
     * is defined as the distance from the origin
     * to that number.</p>
     *
     * @return the modulus of {@code this}
     */
    public T modulus();

    /**
     * <p>returns the complex conjugate of {@code this}</p>
     *
     * <p>The <i>complex conjugate</i> of a complex
     * number {@code z} is defined differently
     * depending on the implementation; therefore,
     * implementations should document which definition
     * is used</p>
     *
     * @return the complex conjugate of {@code this}
     */
    public V conjugate();

    /**
     * <p>negates {@code this}</p>
     *
     * <p>the <i>negation</i> of a complex number
     * {@code z} is defined as the number {@code w}
     * such that the line segment connecting {@code z}
     * to {@code w} also passes through the origin</p>
     * 
     * @return the negation of {@code this}
     */
    public V negate();

    /**
     * <p>Multiplies {@code this} by the element
     * {@code value}, as a ComplexField element</p>
     *
     * <p>{@inheritDoc Field.multiply}</p>
     *
     * @param value the element to be multiplied
     * @return the result of the computation
     *           {@code this*value}, where value
     *           is represented as a Complex Number
     */
    public V multiply(R value);

    /**
     * <p>Adds {@code this} to the element
     * {@code value}, as a ComplexField element</p>
     *
     * <p>{@inheritDoc Field.add}</p>
     *
     * @param value the element to be added
     * @return the result of the computation
     *           {@code this+value}, where value
     *           is represented as a Complex Number
     */
    public V add(R value);

    /**
     * <p>subtracts {@code value} from {@code this}
     *  as a ComplexField element</p>
     *
     * <p>{@inheritDoc Field.subtract}</p>
     *
     * @param value the element to be subtracted
     * @return the result of the computation
     *           {@code this-value}, where value
     *           is represented as a Complex Number
     */
    public V subtract(R value);

    /**
     * <p>divides {@code value} from {@code this}
     *  as a ComplexField element</p>
     *
     * <p>{@inheritDoc Field.divide}</p>
     *
     * @param value the element to be subtracted
     * @return the result of the computation
     *           {@code this/value}, where value
     *           is represented as a Complex Number
     */
    public V divide(R value);



}
